/*
 * To change this template, choose Tools | Templates
 * and open the template in the editor.
 */
package org.yagnus.langutils;

import java.util.Map;

/**
 * 
 * @author hc.busy
 */
public interface AccessibleMap<K, V> extends Map<K, V> {

    /**
     * Sets a default vaule that is retrieved when map normally returns null due to missing entry
     * 
     * @param d
     */
    public void setDefault(V d);

    /**
     * performs same operation as Map.put except when last value of map.get(k) is null, it returns
     * the default value.
     * 
     * @param k
     * @param v
     * @return
     */
    public V putWithDefault(K k, V v);

    /**
     * performs same opration as Map.remove except when returned value is null (k is not in map),
     * this method returns defaultValue.
     * 
     * @param k
     * @return
     */
    public V removeWithDefault(K k);

    /**
     * 
     * Get the current default value.
     * 
     * @param d
     */
    public V getDefault();

    /**
     * Try to get the entry mapped to key k, if not found return default value.s
     * 
     * @param k
     * @return
     */
    public V getWithDefault(K k);

    /**
     * tries to get the key, if it is not mapped, return v instead. but do not update the map.
     * 
     * @param k
     *            The key to find
     * @param v
     *            The value to return in case key is not found.
     * @return what k was mapped to or v is k was nt found.
     */
    public V getWithDefault(K k, V v);

    /**
     * This method is copied from python syntax. returns the value mapped to k in the map if k was
     * mapped; otherwise map k to v, and return v.
     * 
     * @param k
     *            the key to find
     * @param v
     *            the value to map k to (and return) if k was not mapped.
     * @return the value k is mapped to at end of the
     */
    public V getSetToDefault(K k, V v);

    /**
     * Allocate a new one if k is not found
     * 
     * @param k
     * @return
     */
    public V getAllocate(K k);

    public boolean containsValueWithDefault(V v);
}
